{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "o4PAQZyTegH3"
      },
      "source": [
        "<a target=\"_blank\" href=\"https://colab.research.google.com/github/cohere-ai/notebooks/blob/main/notebooks/llmu/Introduction_to_RAG.ipynb\">\n",
        "  <img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/>\n",
        "</a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "EimVurhQ45yk"
      },
      "source": [
        "# Introduction to RAG"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4jBEKety4mKZ"
      },
      "source": [
        "This notebook shows a quickstart example on how to build a RAG-powered chatbot with the Cohere's Chat endpoint. The chatbot can extract relevant information from external documents and produce verifiable, inline citations in its responses.\n",
        "\n",
        "Read the accompanying [article here](https://txt.cohere.com/rag-start/).\n",
        "\n",
        "The diagram below provides an overview of what we’ll build.\n"
      ]
    },
    {
      "attachments": {
        "rag-workflow-1.png": {
          "image/png": "iVBORw0KGgoAAAANSUhEUgAACWwAAAL4CAYAAADlQyw0AAAACXBIWXMAABYlAAAWJQFJUiTwAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAI3TSURBVHgB7N0NuFx1fS/6P4GQFzQJxhBqgkla3gqcBEWEeCsYjtJWtIEWrN6jvJzrbXt7egR629rb3lOgtT7a+hRoPdrT4wV5sdKChVy0tdoS0F7AUF5CgWKkFwIJhWAgCSYkIHD2b9GVs7IyM3vN7Jm15+Xz8ZlnZu+9Zs1aa/aT+cnvu3//fV4dkwAAAAAAAAAAAOi5KQkAAAAAAAAAAIBaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAAAAAAAAAAAGoisAUAAAAAAAAAAFATgS0AAAAAAAAAAICaCGwBAAAAAAAAAADURGALAAAAAAAAAACgJgJbAAAAAAAAAAAANRHYAgAAAAAAAAAAqInAFgAAAAAAAAAAQE0EtgAA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"
        }
      },
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "![rag-workflow-1.png](attachment:rag-workflow-1.png)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "4Qci1A1RNWSU"
      },
      "source": [
        "# Setup"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "KVhenxwXE9oI",
        "outputId": "e1363e93-86cc-407a-d347-0a88d399e955"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "\u001b[?25l     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m0.0/118.8 kB\u001b[0m \u001b[31m?\u001b[0m eta \u001b[36m-:--:--\u001b[0m\r\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m118.8/118.8 kB\u001b[0m \u001b[31m3.7 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m75.6/75.6 kB\u001b[0m \u001b[31m8.2 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m77.8/77.8 kB\u001b[0m \u001b[31m6.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[2K     \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m58.3/58.3 kB\u001b[0m \u001b[31m6.7 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25h"
          ]
        }
      ],
      "source": [
        "! pip install cohere -q"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "cellView": "form",
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 17
        },
        "id": "KiAF_FuHF2Mg",
        "outputId": "2c907cf4-bea5-484a-8e7d-dfe1948a4922"
      },
      "outputs": [
        {
          "data": {
            "text/html": [
              "\n",
              "  <style>\n",
              "    pre {\n",
              "        white-space: pre-wrap;\n",
              "    }\n",
              "  </style>\n",
              "  "
            ],
            "text/plain": [
              "<IPython.core.display.HTML object>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        },
        {
          "data": {
            "text/html": [
              "\n",
              "  <style>\n",
              "    pre {\n",
              "        white-space: pre-wrap;\n",
              "    }\n",
              "  </style>\n",
              "  "
            ],
            "text/plain": [
              "<IPython.core.display.HTML object>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        },
        {
          "data": {
            "text/html": [
              "\n",
              "  <style>\n",
              "    pre {\n",
              "        white-space: pre-wrap;\n",
              "    }\n",
              "  </style>\n",
              "  "
            ],
            "text/plain": [
              "<IPython.core.display.HTML object>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        },
        {
          "data": {
            "text/html": [
              "\n",
              "  <style>\n",
              "    pre {\n",
              "        white-space: pre-wrap;\n",
              "    }\n",
              "  </style>\n",
              "  "
            ],
            "text/plain": [
              "<IPython.core.display.HTML object>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        }
      ],
      "source": [
        "#@title Enable text wrapping in Google Colab\n",
        "\n",
        "from IPython.display import HTML, display\n",
        "\n",
        "def set_css():\n",
        "  display(HTML('''\n",
        "  <style>\n",
        "    pre {\n",
        "        white-space: pre-wrap;\n",
        "    }\n",
        "  </style>\n",
        "  '''))\n",
        "get_ipython().events.register('pre_run_cell', set_css)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "2gY7O7rqE6Nq"
      },
      "outputs": [],
      "source": [
        "import cohere\n",
        "co = cohere.Client(\"COHERE_API_KEY\") # Get your API key here: https://dashboard.cohere.com/api-keys"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "JLXxYR_UHGLJ"
      },
      "source": [
        "# Define documents"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "bKbrq5c1e45y"
      },
      "source": [
        "We define the documents that we want to ground an LLM’s response with, formatted as a list. In our case, each document consists of two fields: title and text.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {
        "id": "CdxeI3XW4yIH"
      },
      "outputs": [],
      "source": [
        "documents = [\n",
        "    {\n",
        "        \"title\": \"Tall penguins\",\n",
        "        \"text\": \"Emperor penguins are the tallest.\"},\n",
        "    {\n",
        "        \"title\": \"Penguin habitats\",\n",
        "        \"text\": \"Emperor penguins only live in Antarctica.\"},\n",
        "    {\n",
        "        \"title\": \"What are animals?\",\n",
        "        \"text\": \"Animals are different from plants.\"}\n",
        "]"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "bT3KjYATHH9o"
      },
      "source": [
        "# Generate response with citations"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "A64u2fIyfBri"
      },
      "source": [
        "Cohere’s RAG functionalities are part of the Chat endpoint, with the Command model as the underlying LLM. This allows developers to build chatbots that have the full context of a conversation and are not limited to a single interaction.\n",
        "\n",
        "First, we define the user message. Then we generate the response from the LLM and display it, together with citations and the source documents used."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 3,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "fkZ6gEYGISWZ",
        "outputId": "662fe3ee-6b61-487b-e59c-c6a18e6038ce"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "The tallest living penguins are emperor penguins, which are found only in Antarctica.\n",
            "\n",
            "CITATIONS:\n",
            "start=32 end=48 text='emperor penguins' document_ids=['doc_0']\n",
            "start=66 end=85 text='only in Antarctica.' document_ids=['doc_1']\n",
            "\n",
            "DOCUMENTS:\n",
            "{'id': 'doc_0', 'text': 'Emperor penguins are the tallest.', 'title': 'Tall penguins'}\n",
            "{'id': 'doc_1', 'text': 'Emperor penguins only live in Antarctica.', 'title': 'Penguin habitats'}\n"
          ]
        }
      ],
      "source": [
        "# Get the user message\n",
        "message = \"What are the tallest living penguins?\"\n",
        "\n",
        "# Generate the response\n",
        "response = co.chat_stream(message=message,\n",
        "                          model=\"command-r-plus\",\n",
        "                          documents=documents)\n",
        "\n",
        "# Display the response\n",
        "citations = []\n",
        "cited_documents = []\n",
        "\n",
        "for event in response:\n",
        "    if event.event_type == \"text-generation\":\n",
        "        print(event.text, end=\"\")\n",
        "    elif event.event_type == \"citation-generation\":\n",
        "        citations.extend(event.citations)\n",
        "    elif event.event_type == \"stream-end\":\n",
        "      cited_documents = event.response.documents\n",
        "\n",
        "# Display the citations and source documents\n",
        "if citations:\n",
        "  print(\"\\n\\nCITATIONS:\")\n",
        "  for citation in citations:\n",
        "    print(citation)\n",
        "\n",
        "  print(\"\\nDOCUMENTS:\")\n",
        "  for document in cited_documents:\n",
        "    print(document)"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "provenance": []
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.11.4"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}
